\magnification 1100
\input pm
\hfil
\vskip 1in
\centerline{\chapfont DVIDIS v3.4}
\bigskip
\centerline{Documentation Version of 6-Apr-88}
\vskip 1in

|DVIDIS| is a program that displays \TeX{} |DVI| files on a
 VaxStation running VWS.

\litem{0in}{\bf NOTE}{5pc}If you have used previous versions of |DVIDIS|,
 note that this
        version is VERY different.  The human interface is much better,
        but most important, the program now reads |PK| format font files,
        not the old, very obsolete |RST| format font files.  It is possible
        to build a version with |RST| file support, but that hasn't been
        tested and is not recommended.  |PK| fonts are MUCH better in every
        way.

\parindent 0pt
Basic usage is very simple.  To display file |TEXT.DVI|, for example, just
type:
\begintt
                $ DVIDIS TEXT
\endtt
on your VAXStation.  A large window will be created, and your text should
start to appear in it; depending on the paper size and where you have located
your window (by default it starts out centered), you may be able to see the
``edge'' of the paper as a gray bar.  Meanwhile, your keyboard will remain
attached to the window you were previously in, and you can enter commands.
For a list of commands available to you, hit the |HELP| key.  The effect of
the various commands is easy to see, so experiment until you feel comfortable
with them.

You can also specify a couple of options on the |DVIDIS| command line.  These
CANNOT be changed once |DVIDIS| has started.  All options are of the form
 ``|-l|''
where ``|l|'' is any single letter, with the single exception of |-verbose| (for
historical reasons).  Some are followed --- after a space --- by one or
 a pair of
numeric arguments; the |-s| command must be followed by a paper size
 specification.

For example:
\begintt
                $ DVIDIS -w -p 2 4 TEXT
\endtt
means ``display pages 2 to 4 of |TEXT.DVI| in 'Wide' mode''.

The following options are commonly used:

\litem{0pt}{|-c|}{5pc}The fonts that |DVIDIS| uses are meant for a 300 dpi
 printer.  A VAXStation display has about 78 dpi.  As a result, 
if you display the glyphs
        from these fonts at a 1--1 pixel-to-pixel mapping, they are about 4
        times as large as they would be on the page, and only about 1/9 of the
        page is visible at a time.  Normally, |DVIDIS| compresses all fonts by a
        2-to-1 factor.  The fonts are still readable, but you can now get most
        of the width of a page --- all, with any reasonable margins --- and 
over
        half the height on the screen.  Specifying ``|-c|'' turns off this
 compression; it's useful mainly for looking at the glyphs, not the text.

\litem{0pt}{|-w|}{5pc}Specifies a 4-to-1 glyph compression factor.
  This allows you to see
        how a whole page looks, but unfortunately it's rather hard to read
        the resulting text.

\litem{0pt}{|-m|}{5pc}Tells |DVIDIS| to try to use smaller fonts,
 rather than compressing
        larger ones.  This only works if you actually HAVE the small fonts on
        your system.  When it works, it improves the appearance of individual
        characters, although it often makes lines come out with slightly
        different lengths than they should.  |-m| is especially useful in
        conjunction with |-w|.  |-m| in conjunction with |-c| is meaningless.

\litem{0pt}{|-s ss|}{5pc}{Set the paper size. This determines what size
        paper the program
        assumes you are printing on.  The default is ``letter'', which is
        8.5 x 11 inches.  The argument is the name of a paper size; type
        |DVIDIS -s ?| for a list of possible values.

      \hang The paper size controls where |DVIDIS| places a visible gray border,
        and when it tells you that characters have ``run off the page''.  It
        always displays the characters, however.

  \hang Paper size ``|huge|'' is meant for special purposes; using it will make
        many of the commands you can type to |DVIDIS| while it is running work
        in strange ways.  You should generally avoid using size ``|huge|''.}

\litem{0pt}{|-verbose|}{5pc}Makes the program talkative.
  This is mainly useful for debugging,
        but since it displays all the font files it opens, successfully or
        not, it can be used to determine which files are needed.  The needed
        files can be created if they don't already exist.  They can also be
        put on your workstation's local disk to improve performance.

\parindent 0pt
The rest of the options are rarely used:

\litem{0pt}{|-v <mi>, -h <mi>|}{8pc}{Set the vertical (horizonal) margin.
  Next argument is the margin, in
        milli-inches.  Default is 1000 milli-inches each, which is the same
        default used by many common |DVI| printing programs.  If you find a lot
        of ``off-screen glyph'' errors, and you have the paper size set
        correctly, try changing these parameters.  (Besides 1000, the second
        most common value expected is 0 for both margins.)

        Note that the default corresponds to the current \TeX{} standard.  If
        you find you have to use some other value to make your output look
        right, some other piece of software you are running is obsolete.}

\litem{0pt}{|-p <s> <e>|}{8pc}Limits the display to pages |<s>|
 through |<e>| inclusive.  You can only
        specify one page range at a time, but you can specify multiple |-p|
        options, each specifying a page range.  When you specify page ranges,
        |DVIDIS| will only ``see'' pages within the ranges given.  Nothing you
        can do while the program is running will let you display any page
        not within any page range --- |DVIDIS| will simply skip past the pages.

\litem{0pt}{|-f|}{8pc}Causes the program to look in ``|USER$RST|'' rather
        than ``|TEX$RST|'' for the
        fonts.  This command is meaningless for the |PK| version of |DVIDIS|,
        and
        of little use even in the |RST| version.

\litem{0pt}{|-d|}{8pc}Debug.  Generates a lot of output that's useful only
 to developers.
\parindent 0pt
\bigskip
{\secfont PROGRAM INSTALLATION}

|DVIDIS| consists of a single image, |DVIDIS.EXE|, that runs on an VAXStation
with VWS V3.0 or later.  It runs as a normal user-mode image, and needs no
special privileges.  |DVIDIS| uses a fair amount of memory as it runs, so be
sure to provide a reasonable working set --- at least 1200 pages, 2000 or more
is better.  In order for |DVIDIS| to receive its arguments, it must be started
with a foreign command line, given by something like:
\begintt
                $ DVIDIS :== $DEV:[DIR]DVIDIS
\endtt
Two ``environment variables'' can be set to control |DVIDIS|, and you can specify
font substitutions.  The environment variables --- typically, logicals, but
if no logicals are defined any |DCL| symbol of the same name will be used ---
are:

\litem{0in}{|DVIDIS\_FILE\_FORMAT|}{9pc}A string that specifies how to
 construct a file specification for
        a font file, given a font name and a dots-per-inch value.  The
        font name will be substituted for |%s|; the dots-per-inch value for
        |%d|.  You must have EXACTLY one of each, in either order; you may
        NOT have any additional occurences of ``|%|''.

        There are two common schemes for storing |PK| font files:

\litem{9pc}{$\bullet$}{10pc}One directory, |DEV:[DIR]|, font
  ``|name|'' at ``|ddd|''
         dots per inch is file |name.dddPK|.  A format string for
                this case would look like \hfil\break ``|DEV:[DIR]%s.%dPK|''.

\litem{9pc}{$\bullet$}{10pc}One root directory, |DEV:[DIR.]|; fonts at
          ``ddd'' dots
                per inch are in subdirectory |[.DPIddd]|, with font
                ``name'' in |name.PK|.  A format string for this case
                would look like ``|DEV:[DIR.DPI%d]%s.PK|''.

\parindent9pc\hangindent\parindent
\hang If |DVIDIS_FILE_FORMAT| is not defined, the default format string
        is \hfil\break ``|TEX_FONTS:[DPI%d]%s.PK|''.
        This corresponds to the second way
        of organizing the font files, and assumes that |TEX_FONTS| is a
        rooted logical translating to something like |DEV:[DIR.]|.

\hang You can only specify a single file format, but that file format
        could involve a logical that translates to a search list.  For
        example, using the default file format, you might do:

\hang |   $ DEFINE TEX_FONTS $DISK1:[TEX.PK.],NODE::TEX_FONTS:|

\hang  where ``|NODE|'' is the name of a node with more fonts than you are
        willing to store locally.  On |NODE|, |TEX_FONTS| must be a SYSTEM
        logical name that translates to a rooted directory.  (If you
        have proxy access to |NODE|, you could define |TEX_FONTS| in your
        login file on |NODE|).  Because of a VMS bug, it isn't possible
        to use something like |NODE::DEV:[DIR.]| to avoid needing a logical
        name on NODE.  (This bug appears in VMS Version 4.5.  If you
        a more recent version, the bug may have been fixed.)

\hang IMPORTANT NOTE

\hang   The definition of |DVIDIS_FILE_FORMAT| will be used as a |printf()|
        format string.  The ``|d|'' and ``|s|'' format specifiers MUST be in
        lower case; if you make them upper case, the format will not
        work.  Note also that |DCL| forces characters to upper case unless
        they are inside a quoted string.  Hence, your definition should
        look something like:

\hang |   $ DEFINE DVIDIS_FILE_FORMAT ``TEX_FONTS:%s.%dPK''|

\litem{0pt}{|DVIDIS\_FONT\_SIZES|}{9pc}This variable must translate to
 a list of all dot-per-inch values
        at which you have any fonts available.  The list consist of just
        the numbers (the ``|ddd|'' values discussed above), separated by
        commas.  |DVIDIS| will never find a font at a size not given in
        the list.

      \hang The default list is:

\hang |100,121,145,174,180,208,210,225,240,250,263,270,274,|\hfil\break
|300,329,360,432,518,622,746,895,896,1074,1075,1289,|\hfil\break
|1290,1547,1548|

\hang which is the list of values I've got.  Extra values will slow
        |DVIDIS| down a bit when it has to open a file, but not by much,
        so you can use the default unless you have some sizes I don't.

\hang Note that this list is NOT a search list, use:

\hang |   $ DEFINE DVIDIS_FONT_SIZES ``300,329,360''|

\hang  WITH THE QUOTATION MARKS.  If you leave the quotation marks off,
        |DVIDIS| will never use anything but the first value you list.
\parindent 0pt
\bigskip
{\secfont FONT SUBSTITUTION}

If |DVIDIS| is unable to find a font as specified, it will check to see if you
have defined a substitute for it in any of three substitution files.  If you
are displaying file |jobname.DVI|, the files are:
\begintt
                jobname.SUB             in the same directory as jobname.DVI;
                TEXFONTS.SUB            in the current directory;
                TEX$INPUTS:TEXFONTS.SUB
\endtt
Every time a substitution is needed, the files present are checked, in the
order given, each from beginning to end, to try to find a substitute.  Only
the first match is used, however.

Each of the substitution files has the same format.  It's a simple ASCII file,
with one substitution per line.  Comments, as in \TeX, are introduced by ``|%|''
and continue to the end of the line.

A substitution line has either of two forms:
\begintt
        oldname.oldsize -> subname.subsize
        oldname         -> subname
\endtt
The first format substitutes only for a particular font name and size.  The
second format substitutes for a particular font name at any size.

Spaces can be used freely in substitution lines.

Since only the first match is used, and the files are always read from the
first line onward, you should specify particular substitutions --- those with
a size --- before generic ones.

It's not an error for the substituted font file not to be found --- |DVIDIS|
 will
proceed to look for ``nearby'' fonts, possibly substituting for them as well.

The |DVIDIS| distribution includes a |TEXFONTS.SUB|
 file that substitutes |CM| fonts
for |AM| fonts.  This should allow you to display |DVI| files
 created using older
versions of \TeX.

\bigskip
{\secfont GETTING THE FIND AND REMOVE KEYPAD KEYS TO WORK}

The |Find| and |Remove| keypad keys use |OSC| functions to control the terminal
window.  |OSC|'s must be enabled; from questions I've received, it seems that
many people are not enabling them.  To enable |OSC|'s, issue the following
command from |DCL| (in a privileged account):
\begintt
        $ DEFINE/SYSTEM/EXEC UIS$VT_ENABLE_OSC_STRINGS TRUE
\endtt

\bigskip
{\secfont KNOWN BUGS AND RESTRICTIONS}

|DVIDIS| is intended to report an error if it can't find a ``close'' match to a
font called for in the file it is displaying.  The test it makes for
 ``closeness'' is wrong, however, so it currently almost never
 reports a problem.  The
result may be grossly distorted output, with no indication that the problem
isn't in the file, it's that |DVIDIS| had to chose an inappropriate font.

Characters actually appearing in the font file, but with no pixels (i.e., a
``0 by 0'' raster) cause |DVIDIS| to crash.  This is known to occur with the
|CMAPL10| font (at least character '040 is a ``space'') and probably will occur
with any of the La\TeX{} ``invisible'' slide fonts.

Stanford Version 2.2 of |PXTOPK|, and all distributed versions to date of
Kellerman and Smith's |PXTOPK| for VMS, have distinct bugs that produce
 completely invalid |PK| files.  Files produced using the Stanford V2.2 code can
be recognized by using |PKTYPE| and looking at the X-offset and Y-offset values
for a couple of characters.  Typical values are small positive or negative
integers --- values outside the range -30 to 30 are very unlikely.  The V2.2
code will produce random, often very large, values.  I don't know the exact
symptoms of the problems the Kellerman and Smith code will produce.  See the
article by Dan Hosek in \TeX hax, Volume 88, \#24 for a discussion.  Version 2.3
of |PXTOPK| fixes the underlying problem; both |PXTOPK.WEB| and a corresponding
version of |PXTOPK.VMS-CHANGES| should be available from ``the usual sources'',
or from the same place you got |DVIDIS|, if all else fails.

|DVIDIS| uses the |dx| field of |PK| fonts to
 determine the width of the characters
it displays.  Width information can also be obtained from the ``|TFM width|''
field.  It seems that most commonly-used |DVI| file drivers use the |TFM| width.
As a result, bugs that result in |PK| files with invalid |dx| values can go
undetected for years.  The most common case, easily detectable with |PKTYPE|,
will have |dx=0| for all the characters.  When such a font is displayed, what
you'll see is bunches of characters displayed at the same position; since
inter-word spacing doesn't depend on the |dx| values, you'll see one ``blotch''
per word.  One place I've seen this come up is with the Hebrew fonts that
come with Jacques Goldberg's Semi\TeX.  Examination of the |GF| files reveals
that they have 0 |dx| values as well, so the problem seems to be some (as-yet
undetermined) inappropriate parameter setting for |Metafont|.  You can work
around this problem by doing a round-about conversion:  Rather than using
|GFTOPK|, use |GFTOPX| (or |PKTOPX|, if you've already got |PK| files),
 then |PXTOPK|.
|PX| files don't store the dx value at all, so a CORRECT |PXTOPK|
 will re-compute
it.

If |DVIDIS_FONT_SIZES| specifies exactly one font size, unpredictable results,
including crashes, may occur.  This shouldn't happen under normal
circumstances, but if you find a distorted display
 and other odd things happening,
it could be that |DVIDIS_FONT_SIZES| is set up wrong.  In particular, make sure
that you've defined it to have a single translation that contains a list of
sizes separated by commas, rather than as multiple translations, each of which
is a single size.  This is discussed above.

If the original \TeX{} run specified a magnification value other than 1000, the
spacing will be incorrect.  The only current work-around is to re-run \TeX{}
without the magnification.  Note that this restriction applies only to GLOBAL
magnifications (i.e., uses of |\magification|).  Individually magnified fonts
are handled correctly.

There is a bug in the VAX C library for Versions 4.6 and 4.7 of VMS that will
cause |DVIDIS| to die with a Reserved Operand Fault if it runs out of memory.
The only work-around is to increase the amount of virtual memory available
to the process running |DVIDIS|.  (Note that, without the bug, |DVIDIS| would
try to recover by discarding some font information it has already read in.
The resulting performance loss would probably be substantial, so you'd
probably want to run with a larger virtual memory limit anyway.
  On a workstation, there is little reason NOT to run this way in any case.
  You'll
probably want to allow big working sets, too.)


\litem{0in}{Author:}{4pc}Jerry Leichter, based on work of Bill Gropp's,
 which in turn was
based on a lot of earlier work by others; with additional input from Bert
Beander at DEC.  Comments/questions/suggestions to Jerry Leichter at

\hang LEICHTER-JERRY@CS.YALE.EDU\hfil\break
            or\hfil\break
      LEICHTER@YALEVMS.BITNET

\bye
